In Kanzi a resource is an item you can reuse in different parts of your application. For example, a Mesh Data resource defines the geometry of a Model node and you can use the same Color Brush brush in different nodes to set the Foreground Brush or Background Brush properties. Kanzi resource manager enables you to organize and reuse resources in your applications.
In Kanzi you can set the resources to nodes either directly using the resource URL, or indirectly using the resource key. When you set resources in Kanzi Studio, it by default assigns all resources using the URL. If you want to use the indirect setting in Kanzi Studio you need to create a key for the resource in a resource dictionary, and in the property select that key. Because key lookup is hierarchical you can define what the key resolves to by creating resource dictionary entries in the tree.
Setting resources using resource keys enables you to:
You can share the resources to decrease the memory and runtime requirements of your application. This enables you to reuse the same resource, or to change the resource so that the change is reflected in the entire application. For example, that way you can share a brush that is animated.
Kanzi offers many tools to manage the resources while the application is running. In Kanzi you can:
| Kanzi resource | Documentation |
|---|---|
| Aliases. Use an Alias to get consistent access to a Kanzi node. You can use aliases to access nodes both in Kanzi Studio and using the Kanzi Engine API or scripting. | Using aliases |
|
Animation Clip.Use an Animation Clip to combine Animation Data resources into more complex animations. You can reuse the same Animation Data resources in different Animation Clip items. Use an Animation Child Clip to create hierarchical animations. Animation Data. Use an Animation Data resource to define the keyframes and target property of a keyframe animation. One Animation Data resource can target only one property or property attribute. Animation Data resources are independent from the nodes they target. This allows you to reuse Animation Data resources to animate different nodes. Timeline Sequence. Use a Timeline Sequence to combine a set of Timeline Entry resources. |
|
|
Brushes. Use brushes to set the background of 2D nodes. In Kanzi all 2D nodes by default have transparent background. Fonts. Use fonts to render text. |
|
|
Materials. Use materials to set the appearance of Model nodes and Material Brush brushes. Mesh Data. A mesh is a collection of vertices, edges, and faces that define the shape of a solid object in 3D with flat faces and straight edges and the triangles that form the surface between the points. Textures. Use textures to show content in Image nodes, to set the look of textured materials, and to show content in Texture Brush brushes. You can create textures from common image file formats. |
|
|
Render Passes. Use render passes to define the rendering of nodes in your Kanzi application. Object Source. Use object sources and filters to tell a Draw Objects Render Pass which nodes in your Kanzi application you want to render. Root Object Source contains all nodes in the scene graph of the currently active Scene node. |
|
| Resource Dictionary. A resource dictionary is a collection of a key-value pair entries for each resource. | Resources |
| Scripts. Use JavaScript scripts to program the logic and look of your application right in Kanzi Studio. | Using scripts |
| State Managers. Use a State Manager to create different states in your Kanzi application. | State manager |
| Styles. Use styles to set the property values of one or more nodes of a certain type. | Using styles |
| Text Resources. A text resource is a text string used by Text Block 3D and Text Block 3D nodes. | Using the Text Block nodes |
| Trajectories. Use trajectories as paths along which Trajectory Layout 3D and Trajectory Layout 2D nodes arrange their child nodes, and along which Trajectory List Box 3D nodes move their items. | Trajectories |
You can create some resources directly in Kanzi Studio (for example, brushes and animations). For some resources you have to import assets created in third-party tools (for example, textures and meshes). See Importing.
The most basic way to refer to a resource is a URL. URLs can refer to resources inside a kzb file or files on device storage. When you set a resource in a property you need to provide the URL of the resource. When you do that in Kanzi Studio in the Properties window, Kanzi does that automatically for the resource you select. When you set resource properties using the API or a script, you need to provide the resource URL manually. To find the URL of a resource in your project, in Kanzi Studio right-click the resource and select Copy .kzb URL. To reference files on the device storage use the file:/// URL format.
When using the API you can specify a resource object directly. Nodes that accept resource objects usually provide a method overload that accepts such objects. For example, to set the image in an Image node use Image2D::setImage.
A resource dictionary is a collection of a key-value pair entries for each resource. You can define a resource dictionary in any node. Keys provide means to specify resources indirectly: instead of specifying a resource or a URL to a node, you can specify a key. Kanzi resolves the resource dynamically by looking up the nearest resource dictionary where the key defines to which resource it resolves to. When a key needs to be resolved to an item, the resolving process starts checking the resource dictionaries from the node that uses the key: if a dictionary of that node contains the key, the node uses that key, if not, the node checks its parents' dictionaries until it finds the key. This process continues recursively until the root of the scene graph. If the node does not find the key, it is up to the node to decide what happens then. For example, it is a valid case if an Image node does not show an image. Kanzi controls fail softly when resources are not found, but in plugins it is up to the author of the plugin to define what happens.
Kanzi comes with default resources that enable you to create applications faster. For example, when you create a Scene, Kanzi provides a default render pass, when you create a Text Block 2D or a Text Block 3D node, Kanzi provides a default font. If you need to customize the default Kanzi resources, create or import the resources that fit your needs and use them instead of the Kanzi default resources.
When you create a kzb file from your Kanzi Studio project the default Kanzi resources are included in the kzb file by default.
The resource manager manages the lifetime, loading, and unloading of resources. You can access the resource manager using the Kanzi API and you can use it to specify the lifetime policies for resources and to remove unused resources. To specify whether resources are always kept in memory, or unloaded when they are not needed, you specify a policy. You can specify a policy globally for the resource manager, or for each resource. If the policy is to keep the resources in memory, you can request manual removal based on the logic of your application. For example, you can manually remove resources when you change a Page node in your application to load a large amount of resources for a new Page node.
The resource manager allows you to define in which memory the GPU resources in your Kanzi application are stored. For example, to set this for a texture in Kanzi Studio in the Library > Materials and Textures > Textures select a texture and in the Properties set the GPU Memory Type property:
When your application suspends, the GPU resources not stored in a kzb file become invalid. Destroy these resources and recreate them on resume. Make sure that after recreating a resource the pointers are correct. Kanzi automatically restores all other resources.
Setting how Kanzi Engine handles unused resources
